1. 3D Secure 2
3D Secure (3DS) es un protocolo de autenticación que tiene como objetivo reducir el fraude, aumentar la seguridad del titular de la tarjeta y reducir la responsabilidad del comercio por las devoluciones. Se introduce un paso en el proceso de transacción en el que se muestra al cliente una pantalla alojada por o en nombre de su Emisor y se le solicita que se autentique, a menudo a través de una contraseña o información similar que solo el cliente conoce.
3DS 2 está diseñado teniendo en cuenta la experiencia de pago móvil mediante la introducción de nuevos flujos de pago que se adaptan mejor a los clientes que pagan en el móvil con nuevos métodos de autenticación, como la biometría, o la opción de un flujo sin fricciones mediante el uso de un conjunto de datos más completo proporcionado por el comercio para autenticar al cliente sin necesidad de su intervención.
La página de pago alojada de Addon Payments gestionará todo el flujo de autenticación de 3D Secure, incluida la determinación de qué versión de 3D Secure utilizar, la recopilación de la información necesaria del dispositivo y la presentación del desafío al cliente si es necesario. Finalmente, el HPP procesará la autorización con la información de autenticación adicional transmitida al Emisor.
1.1 Exenciones
Una de las ventajas clave de 3D Secure 2 es que proporciona un marco para que los comercios se beneficien de las exenciones de SCA en determinadas condiciones. La idea detrás de estas exenciones es permitir el desarrollo de una experiencia de pago fácil de usar en circunstancias donde el riesgo es bajo.
El Emisor puede aplicar exenciones en función de los detalles de la transacción o el comercio puede solicitarlas específicamente, con el permiso de su Adquirente. En el mensaje de autenticación, puede solicitar una exención incluyéndola en el campo "Challenge indicator" (consulte la nota a continuación).
Cuando un comercio solicita una exención, ya no podrá hacer uso de un cambio de responsabilidad en caso de una devolución de cargo. --> Para solicitudes de exención de Mastercard, consulte también nuestra documentación de Extensión de mensajes de Mastercard.
2. Petición
En este ejemplo, solo estamos pasando campos obligatorios junto con algunos recomendados. Cuantos más campos opcionales envíe y los datos que proporcione, es más probable que la autenticación de la transacción sea fluida. Para obtener la lista completa de campos opcionales y los valores permitidos en cada uno, consulte la sección "Datos opcionales 3DS2 HPP".
<?php
// Imports necesarios para realizar una aturoización
require_once('vendor/autoload.php');
use AddonPayments\Api\Entities\Address;
use AddonPayments\Api\Entities\Enums\AddressType;
use AddonPayments\Api\ServicesConfig;
use AddonPayments\Api\HostedPaymentConfig;
use AddonPayments\Api\Entities\HostedPaymentData;
use AddonPayments\Api\Entities\Enums\HppVersion;
use AddonPayments\Api\Entities\Exceptions\ApiException;
use AddonPayments\Api\Services\HostedService;
// Configuración del terminal
$config = new ServicesConfig();
$config->merchantId = "Merchant_ID";
$config->accountId = "Sub_Account";
$config->sharedSecret = "Shared_Secret";
$config->serviceUrl = "URL";
$config->hostedPaymentConfig = new HostedPaymentConfig();
$config->hostedPaymentConfig->version = HppVersion::VERSION_2;
$service = new HostedService($config);
// Añadimos los campos obligatorios de 3DS2 del cliente
$hostedPaymentData = new HostedPaymentData();
$hostedPaymentData->customerEmail = "custoemr@email.com";
$hostedPaymentData->customerPhoneMobile = "34|914353028";
$hostedPaymentData->addressesMatch = True;
// Añadimos los campos obligatorios de 3DS2 de dirección de facturación
$billingAddress = new Address();
$billingAddress->streetAddress1 = "Dirección de facturación 1";
$billingAddress->streetAddress2 = "Dirección de facturación 2";
$billingAddress->streetAddress3 = "Dirección de facturación 3";
$billingAddress->city = "Ciudad de facturación";
$billingAddress->postalCode = "Código postal de facturación";
$billingAddress->country = "País de facturación";
// Añadimos los campos obligatorios de 3DS2 de dirección de envío
$shippingAddress = new Address();
$shippingAddress->streetAddress1 = "Dirección de envío 1";
$shippingAddress->streetAddress2 = "Dirección de envío 2";
$shippingAddress->streetAddress3 = "Dirección de envío 3";
$shippingAddress->city = "Ciudad de envío";
$shippingAddress->state = "Código ISO del país de envío";
$shippingAddress->postalCode = "Código postal de envío";
$shippingAddress->country = "País de envío";
// Lanzamos la petición al servidor de Addon Payments
try {
$hppJson = $service->charge(20)
->withCurrency("EUR")
->withHostedPaymentData($hostedPaymentData)
->withAddress($billingAddress, AddressType::BILLING)
->withAddress($shippingAddress, AddressType::SHIPPING)
->serialize();
// Mostramos el formulario
echo $hppJson;
} catch (ApiException $e) {
// Añada aquí su tratamiento de errores
echo $e->getMessage();
}
?>
2.1 Configuración del terminal
Debemos introducir los datos de configuración que se facilitan en la llamada de cualificación del soporte técnico de Addon Payments.
- Merchant_ID = Identificador del comercio.
- SubAccount = Subcuenta faciltiada en la llamada de cualificación (si se deja en blanco se envía la subcuenta por defecto que le hayan creado).
- Shared Secret = Contraseña de seguridad del terminal.
<?php
$config = new ServicesConfig();
$config->merchantId = "Merchant_ID";
$config->accountId = "Sub_Account";
$config->sharedSecret = "Shared_Secret";
$config->serviceUrl = "URL";
$config->hostedPaymentConfig = new HostedPaymentConfig();
// Debemos enviar la versión 2 de HPP_VERSION
$config->hostedPaymentConfig->version = HppVersion::VERSION_2;
$config->hostedPaymentConfig = new HostedService($config);
?>
2.2 Campos obligatorios
Debemos enviar la información recopilada del cliente:
- Teléfono
- Indicar a "True" si la dirección de facturación y envío es la misma
- Dirección de facturación y envío del cliente
<?php
// Cliente
$hostedPaymentData = new HostedPaymentData();
$hostedPaymentData->customerEmail = "custoemr@email.com";
$hostedPaymentData->customerPhoneMobile = "34|914353028";
$hostedPaymentData->addressesMatch = True;
// Facturación
$billingAddress = new Address();
$billingAddress->streetAddress1 = "Dirección de facturación 1";
$billingAddress->streetAddress2 = "Dirección de facturación 2";
$billingAddress->streetAddress3 = "Dirección de facturación 3";
$billingAddress->city = "Ciudad de facturación";
$billingAddress->postalCode = "Código postal de facturación";
$billingAddress->country = "País de facturación";
// Envío
$shippingAddress = new Address();
$shippingAddress->streetAddress1 = "Dirección de envío 1";
$shippingAddress->streetAddress2 = "Dirección de envío 2";
$shippingAddress->streetAddress3 = "Dirección de envío 3";
$shippingAddress->city = "Ciudad de envío";
$shippingAddress->state = "Código ISO del país de envío";
$shippingAddress->postalCode = "Código postal de envío";
$shippingAddress->country = "País de envío";
?>
2.3 Envío de la operación archivo PHP
Para enviar la operación debemos emplear el modelo de excepciones "try - catch". -->Para obtener más información sobre la excepción de "try - catch" puede ver la documentación oficial de PHP.
- Llamamos al objeto "$hppJson" e indicamos el importe que queremos cargar: $service ->charge(20)
- Posteriormente debemos indicar la moneda en la que vamos a realizar el cargo: ->withCurrency("EUR")
- Debemos indicar los datos recopilados del cliente: ->withHostedPaymentData($hostedPaymentData)
-
Indicamos también la dirección de envío y facturación del cliente:
->withAddress($billingAddress, AddressType::BILLING)
->withAddress($shippingAddress, AddressType::SHIPPING) - Por último, enviamos la petición: ->serialize();
<?php
// Lanzamos la petición al servidor de Addon Payments
try {
$hppJson = $service->charge(20)
->withCurrency("EUR")
->withHostedPaymentData($hostedPaymentData)
->withAddress($billingAddress, AddressType::BILLING)
->withAddress($shippingAddress, AddressType::SHIPPING)
->serialize();
// Mostramos el formulario
echo $hppJson;
} catch (ApiException $e) {
// Añada aquí su tratamiento de errores
echo $e->getMessage();
}
?>
Para la respuesta realizamos un echo de la función "getMessage()".
Con esta función obtenemos el motivo de la denegación del servidor. Para ver todos los errores de denegación actualizados, puede comprobar nuestra documentación de Addon Payments.
2.4 Envío de la operación archivo HTML
Para lanzar la operación desde nuestro HTML, debemos emplear lo siguientes parámetros:
- Indicamos la ruta del archivo PHP que realiza la petición al servidor de PHP: $.getJSON("request.php")
- Posteriormente debemos indicar la URL del servidor de Addon Payments: setHppUrl("https://hpp.sandbox.addonpayments.com/pay");
- Por último, debemos indicar el identificador del botón y la ruta del archivo de respuesta: redirect.init("payButtonId", "response.php");
<script>
$(document).ready(function() {
$.getJSON("request.php", function(jsonFromRequestEndpoint) {
RealexHpp.setHppUrl("https://hpp.sandbox.addonpayments.com/pay");
RealexHpp.redirect.init("payButtonId", "response.php", jsonFromRequestEndpoint);
});
});
</script>
3. Flujos de autenticación
En este punto, el Emisor analizará la transacción. Tendrá en cuenta factores como los datos que su aplicación ha proporcionado junto con el comportamiento histórico del cliente y el análisis de transacciones. El resultado de este proceso determinará si el Emisor decide que el cliente debe autenticar aún más la transacción y realizar una comprobación con el ACS (flujo con fricción).
3.1 Flujo sin fricción
En un flujo sin fricciones, el Emisor puede determinar que no se requiere autenticación adicional, que la transacción puede continuar. O en base a la información que ha recibido hasta ahora, que la transacción no debería continuar.
En un escenario de transacción bloqueada, Addon Payments devolverá un mensaje de respuesta de falla a su aplicación/sitio web y puede optar por redirigir al cliente a la página de pago mientras le informa del resultado. De lo contrario, el HPP completará el proceso de autenticación y procederá a la autorización, incluidos los datos de autenticación de 3D Secure.
3.2 Flujo con fricción
En el caso de un flujo de fricción, el Emisor ha determinado que el cliente debe autenticar aún más la transacción. El HPP mostrará el Emisor ACS al cliente. El desafío puede implicar una serie de pasos, incluido que el cliente ingrese una contraseña de un solo uso enviada a su teléfono o responda algunas preguntas que solo él sabría responder.
El Emisor ACS determinará el tipo de desafío que se mostrará al cliente y se alineará con al menos dos elementos de la autenticación sólida del cliente (SCA):
- Possession: Algo que solo el cliente tiene, por ejemplo, su dispositivo móvil registrado en su banco en el que recibirá un código en un SMS.
- Inherence: Su huella digital u otra forma de datos biométricos.
- Knowledge: Una frase de contraseña única o la respuesta a una pregunta personal.
3.3 Simulador ACS
En el entorno sandbox (pruebas), Addon Payments proporciona un simulador de Emisor ACS que le permite probar diferentes resultados de desafíos.
Una vez que se haya cargado el desafío, después de diez segundos, el simulador completará automáticamente la autenticación y generará una respuesta de Autenticación exitosa (transStatus = “Y”). Esto tiene la intención de imitar un escenario en el que un cliente ha recibido una notificación en su teléfono para autenticarse usando su aplicación bancaria.
Para simular una autenticación fallida, hacer clic en el botón "Cancelar" generará una respuesta fallida (transStatus = “N”). En cualquier escenario, el resultado se enviará en el mensaje de respuesta de desafío (CRes) al punto final de notificación de desafío.
3.4 Resultado del desafío
Con el cliente en el ACS, pueden ocurrir los siguientes resultados:
- La autenticación es exitosa.
- La autenticación falla y el cliente no tiene otra oportunidad.
- La autenticación falla y el cliente tiene otra oportunidad.
Si el cliente ha completado con éxito el desafío y se ha autenticado, Addon Payments procederá a la autorización e incluirá los datos de autenticación de 3D Secure. Alternativamente, en un escenario de transacción bloqueada, HPP devolverá un mensaje de respuesta de fallo (110).
En este punto, tanto en escenarios sin fricciones como en escenarios de desafío, la transacción puede autorizarse o declinarse de manera normal en función de si el cliente tiene fondos suficientes en su cuenta o si ingresó su código de seguridad correctamente, etc. Addon Payments devolverá la respuesta de la transacción junto con los datos de autenticación de 3D Secure adicionales que puede capturar en su sitio web/aplicación.
4. Formulario de ejemplo
Para poder procesar la transacción con el formulario de ejemplo, debe modificar el archivo "Authorization.php" que se encuentra en la ruta "vendor\addonpayments\php-sdk\test\php\HPP\05 - 3DS2\01 - Autorización".
Debe introducir sus datos de configuración tal y como se muestra en el punto 2.1 de esta guía.
4.1 Formulario
El siguiente formulario le permite enviar una operación contra el entorno de pruebas de Addon Payments.